From 7b168e71eb186d996e797f8100265ea9413c457a Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 2 May 2002 22:28:50 +0000 Subject: [PATCH] Doc updates. --- ChangeLog | 12 +++++++ ChangeLog.pre-2-10 | 12 +++++++ ChangeLog.pre-2-2 | 12 +++++++ ChangeLog.pre-2-4 | 12 +++++++ ChangeLog.pre-2-6 | 12 +++++++ ChangeLog.pre-2-8 | 12 +++++++ docs/reference/ChangeLog | 12 ++++++- docs/reference/gdk/gdk-sections.txt | 1 - docs/reference/gdk/tmpl/gdkdisplay.sgml | 4 +-- docs/reference/gdk/tmpl/gdkscreen.sgml | 15 ++------- docs/reference/gdk/tmpl/x_interaction.sgml | 25 +++++++++------ gdk/gdkscreen.c | 13 ++++---- gdk/x11/gdkdisplay-x11.c | 17 ++++++++++ gdk/x11/gdkdnd-x11.c | 11 +++++++ gdk/x11/gdkfont-x11.c | 37 ++++++++++++++++++++++ gdk/x11/gdkkeys-x11.c | 15 ++++++--- gdk/x11/gdkscreen-x11.c | 16 ++++++++++ 17 files changed, 199 insertions(+), 39 deletions(-) diff --git a/ChangeLog b/ChangeLog index ec316cc394..3ee815c231 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,17 @@ 2002-05-02 Matthias Clasen + * gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment. + + * gdk/x11/gdkdisplay-x11.c (gdk_open_display): + * gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): + * gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): + * gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): + * gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document. + * gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix. * gtk/gtkwidget.c (gtk_widget_class_init): Correct the diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index ec316cc394..3ee815c231 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,5 +1,17 @@ 2002-05-02 Matthias Clasen + * gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment. + + * gdk/x11/gdkdisplay-x11.c (gdk_open_display): + * gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): + * gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): + * gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): + * gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document. + * gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix. * gtk/gtkwidget.c (gtk_widget_class_init): Correct the diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index ec316cc394..3ee815c231 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,5 +1,17 @@ 2002-05-02 Matthias Clasen + * gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment. + + * gdk/x11/gdkdisplay-x11.c (gdk_open_display): + * gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): + * gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): + * gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): + * gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document. + * gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix. * gtk/gtkwidget.c (gtk_widget_class_init): Correct the diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index ec316cc394..3ee815c231 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,5 +1,17 @@ 2002-05-02 Matthias Clasen + * gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment. + + * gdk/x11/gdkdisplay-x11.c (gdk_open_display): + * gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): + * gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): + * gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): + * gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document. + * gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix. * gtk/gtkwidget.c (gtk_widget_class_init): Correct the diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index ec316cc394..3ee815c231 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,5 +1,17 @@ 2002-05-02 Matthias Clasen + * gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment. + + * gdk/x11/gdkdisplay-x11.c (gdk_open_display): + * gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): + * gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): + * gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): + * gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document. + * gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix. * gtk/gtkwidget.c (gtk_widget_class_init): Correct the diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index ec316cc394..3ee815c231 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,5 +1,17 @@ 2002-05-02 Matthias Clasen + * gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment. + + * gdk/x11/gdkdisplay-x11.c (gdk_open_display): + * gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): + * gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): + * gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen): + * gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): + * gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): + * gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document. + * gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix. * gtk/gtkwidget.c (gtk_widget_class_init): Correct the diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 734f9c7b36..17b88f436a 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,4 +1,14 @@ -2002-05-02 Matthias Clasen +2002-05-03 Matthias Clasen + + * gdk/gdk-sections.txt: Remove gdk_screen_use_virtual_screen. + + * gdk/tmpl/gdkscreen.sgml: Updates. + + * gdk/tmpl/gdkdisplay.sgml: Document GdkDisplay. + + * gdk/tmpl/x_interaction.sgml: Document GDK_DISPLAY_XDISPLAY, + GDK_SCREEN_XDISPLAY, GDK_SCREEN_XSCREEN, GDK_SCREEN_XNUMBER, + gdk_font_lookup_for_display. * gdk/Makefile.am (GTKDOC_CFLAGS, GTKDOC_LIBS): set these. diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt index 1298b56583..8c111d67bf 100644 --- a/docs/reference/gdk/gdk-sections.txt +++ b/docs/reference/gdk/gdk-sections.txt @@ -167,7 +167,6 @@ gdk_screen_get_height_mm gdk_screen_close gdk_screen_list_visuals gdk_screen_get_toplevel_windows -gdk_screen_use_virtual_screen gdk_screen_get_n_monitors gdk_screen_get_monitor_geometry gdk_screen_get_monitor_at_point diff --git a/docs/reference/gdk/tmpl/gdkdisplay.sgml b/docs/reference/gdk/tmpl/gdkdisplay.sgml index 7962c66399..65504c1934 100644 --- a/docs/reference/gdk/tmpl/gdkdisplay.sgml +++ b/docs/reference/gdk/tmpl/gdkdisplay.sgml @@ -30,10 +30,10 @@ controls the keyboard/mouse pointer grabs and a set of GdkScreens - +The GdkDisplay struct is the GDK representation +of an X display. All its fields are private and should not be accessed directly. -@parent_instance: diff --git a/docs/reference/gdk/tmpl/gdkscreen.sgml b/docs/reference/gdk/tmpl/gdkscreen.sgml index db18d3e0b5..d423d554e1 100644 --- a/docs/reference/gdk/tmpl/gdkscreen.sgml +++ b/docs/reference/gdk/tmpl/gdkscreen.sgml @@ -24,12 +24,10 @@ form a large screen area. -This is a currently just a placeholder typedef for the first argument of -the @window_at_pointer function in #GdkPointerHooks. It will be used -when GDK gets multihead support. +The GdkScreen struct is the GDK representation of a + physical screen. All its fields are private and should not be accessed directly. -@parent_instance: @@ -185,15 +183,6 @@ when GDK gets multihead support. @Returns: - - - - - -@screen: -@Returns: - - diff --git a/docs/reference/gdk/tmpl/x_interaction.sgml b/docs/reference/gdk/tmpl/x_interaction.sgml index 4174cb4af4..292f8518cc 100644 --- a/docs/reference/gdk/tmpl/x_interaction.sgml +++ b/docs/reference/gdk/tmpl/x_interaction.sgml @@ -78,10 +78,10 @@ Returns the X pixmap belonging to a #GdkPixmap. - +Returns the display of a #GdkDisplay. -@display: +@display: a #GdkDisplay. @@ -149,26 +149,30 @@ Returns the X colormap belonging to a #GdkColormap. - +Returns the display of a #GdkScreen. -@screen: +@screen: a #GdkScreen. +@Returns: an Xlib Display*. - +Returns the index of a #GdkScreen. -@screen: +@screen: a #GdkScreen +@Returns: the position of @screen among the screens of + its display. - +Returns the screen of a #GdkScreen. -@screen: +@screen: a #GdkScreen +@Returns: an Xlib Screen*. @@ -370,7 +374,7 @@ a #GdkWindow or a #GdkFont. -Obtains the #GdkFont for the given Xlib pixmap ID, or %NULL if no #GdkPixmap has +Obtains the #GdkFont for the given Xlib font ID, or %NULL if no #GdkFont has been created for @xid. @@ -379,7 +383,8 @@ been created for @xid. - +Obtains the #GdkFont for the given Xlib font ID on @display, or %NULL if no +#GdkFont has been created for @xid. @display: diff --git a/gdk/gdkscreen.c b/gdk/gdkscreen.c index 415ff27229..078134d07f 100644 --- a/gdk/gdkscreen.c +++ b/gdk/gdkscreen.c @@ -317,14 +317,13 @@ gdk_screen_get_monitor_at_point (GdkScreen *screen, } /** - * gdk_screen_get_monitor_num_at_window: - * @screen : a #GdkScreen. - * @anid : a #GdkDrawable ID. - * - * Returns the monitor number in which the largest area of the bounding rectangle - * of @anid resides. + * gdk_screen_get_monitor_at_window: + * @screen: a #GdkScreen. + * @window: a #GdkWindow + * @returns: the monitor number in which most of @window is located. * - * Returns: the monitor number in which most of @anid is located. + * Returns the number of the monitor in which the largest area of the bounding rectangle + * of @window resides. **/ gint gdk_screen_get_monitor_at_window (GdkScreen *screen, diff --git a/gdk/x11/gdkdisplay-x11.c b/gdk/x11/gdkdisplay-x11.c index e700981805..9f1425397b 100644 --- a/gdk/x11/gdkdisplay-x11.c +++ b/gdk/x11/gdkdisplay-x11.c @@ -215,6 +215,14 @@ init_xinerama_support (GdkScreen * screen) screen_x11->monitors[0].height = HeightOfScreen (screen_x11->xscreen); } +/** + * gdk_open_display: + * @display_name: the name of the display to open + * @returns: a #GdkDisplay, or %NULL if the display + * could not be opened. + * + * Opens a display. + */ GdkDisplay * gdk_open_display (const gchar *display_name) { @@ -634,8 +642,17 @@ _gdk_x11_display_screen_for_xrootwin (GdkDisplay *display, return NULL; } +/** + * gdk_x11_display_get_xdisplay: + * @display: a #GdkDisplay + * @returns: an X display. + * + * Returns the X display of a #GdkDisplay. + */ Display * gdk_x11_display_get_xdisplay (GdkDisplay *display) { return GDK_DISPLAY_X11 (display)->xdisplay; } + + diff --git a/gdk/x11/gdkdnd-x11.c b/gdk/x11/gdkdnd-x11.c index 7aa0bbf871..a387bf5200 100644 --- a/gdk/x11/gdkdnd-x11.c +++ b/gdk/x11/gdkdnd-x11.c @@ -2715,6 +2715,17 @@ gdk_drag_begin (GdkWindow *window, return new_context; } +/** + * gdk_drag_get_protocol_for_display: + * @display: the #GdkDisplay where the destination window resides + * @xid: the X id of the destination window. + * @protocol: location where the supported DND protocol is returned. + * @returns: the X id of the window where the drop should happen. This + * may be @xid or the X id of a proxy window, or None if @xid doesn't + * support Drag and Drop. + * + * Finds out the DND protocol supported by a window. + */ guint32 gdk_drag_get_protocol_for_display (GdkDisplay *display, guint32 xid, diff --git a/gdk/x11/gdkfont-x11.c b/gdk/x11/gdkfont-x11.c index 825934e8d9..df962da1ab 100644 --- a/gdk/x11/gdkfont-x11.c +++ b/gdk/x11/gdkfont-x11.c @@ -162,6 +162,17 @@ gdk_font_hash_lookup (GdkDisplay *display, } } +/** + * gdk_font_load_for_display: + * @display: a #GdkDisplay + * @font_name: a XLFD describing the font to load. + * @returns: a #GdkFont, or %NULL if the font could not be loaded. + * + * Loads a font for use on @display. + * + * The font may be newly loaded or looked up the font in a cache. + * You should make no assumptions about the initial reference count. + */ GdkFont * gdk_font_load_for_display (GdkDisplay *display, const gchar *font_name) @@ -254,6 +265,20 @@ gdk_font_charset_for_locale (void) return g_strdup ("iso8859-1"); }; +/** + * gdk_font_from_description_for_display: + * @display: a #GdkDisplay + * @font_desc: a #PangoFontDescription. + * + * Loads a #GdkFont based on a Pango font description for use on @display. + * This font will only be an approximation of the Pango font, and + * internationalization will not be handled correctly. This function + * should only be used for legacy code that cannot be easily converted + * to use Pango. Using Pango directly will produce better results. + * + * Return value: the newly loaded font, or %NULL if the font + * cannot be loaded. + */ GdkFont * gdk_font_from_description_for_display (GdkDisplay *display, PangoFontDescription *font_desc) @@ -315,6 +340,18 @@ gdk_font_from_description (PangoFontDescription *font_desc) return gdk_font_from_description_for_display (gdk_get_default_display (),font_desc); } +/** + * gdk_fontset_load_for_display: + * @display: a #GdkDisplay + * @fontset_name: a comma-separated list of XLFDs describing + * the component fonts of the fontset to load. + * @returns: a #GdkFont, or %NULL if the fontset could not be loaded. + * + * Loads a fontset for use on @display. + * + * The fontset may be newly loaded or looked up in a cache. + * You should make no assumptions about the initial reference count. + */ GdkFont * gdk_fontset_load_for_display (GdkDisplay *display, const gchar *fontset_name) diff --git a/gdk/x11/gdkkeys-x11.c b/gdk/x11/gdkkeys-x11.c index d0bf2794a0..7c0dc100b0 100644 --- a/gdk/x11/gdkkeys-x11.c +++ b/gdk/x11/gdkkeys-x11.c @@ -166,12 +166,11 @@ get_xkb (GdkKeymapX11 *keymap_x11) */ /** - * gdk_keymap_get_for_display : - * @display : the #GdkDisplay. + * gdk_keymap_get_for_display: + * @display: the #GdkDisplay. + * @returns: the #GdkKeymap attached to @display. * - * Returns the GdkKeymap attached to @display. - * - * Returns : the GdkKeymap attached to @display. + * Returns the #GdkKeymap attached to @display. **/ GdkKeymap* gdk_keymap_get_for_display (GdkDisplay *display) @@ -188,6 +187,12 @@ gdk_keymap_get_for_display (GdkDisplay *display) return display_x11->keymap; } +/** + * gdk_keymap_get_default: + * @returns: the #GdkKeymap attached to the default display. + * + * Returns the #GdkKeymap attached to the default display. + **/ GdkKeymap* gdk_keymap_get_default (void) { diff --git a/gdk/x11/gdkscreen-x11.c b/gdk/x11/gdkscreen-x11.c index 5113986a43..559b2e3472 100644 --- a/gdk/x11/gdkscreen-x11.c +++ b/gdk/x11/gdkscreen-x11.c @@ -255,12 +255,28 @@ gdk_screen_x11_get_monitor_geometry (GdkScreen *screen, *dest = screen_x11->monitors[num_monitor]; } +/** + * gdk_x11_screen_get_xscreen: + * @screen: a #GdkScreen. + * @returns: an Xlib Screen* + * + * Returns the screen of a #GdkScreen. + */ Screen * gdk_x11_screen_get_xscreen (GdkScreen *screen) { return GDK_SCREEN_X11 (screen)->xscreen; } + +/** + * gdk_x11_screen_get_screen_number: + * @screen: a #GdkScreen. + * @returns: the position of @screen among the screens of + * its display. + * + * Returns the index of a #GdkScreen. + */ int gdk_x11_screen_get_screen_number (GdkScreen *screen) { -- 2.30.2